home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / raytrace / pov / gen / pvcoil21 / coil.doc < prev    next >
Encoding:
Text File  |  1993-09-17  |  11.2 KB  |  244 lines
  1. COIL.EXE v2.0  7/25/92 W. D. Kirby
  2. COIL.EXE v2.1  9/14/93 R. Bryerton
  3.  
  4. Description:
  5.  
  6.    COIL.EXE is a simple utility to create an endless coil type object for
  7. the Persistance of Vision (PoV-Ray v1.0) and Polyray v1.6 raytracers.  
  8. COIL.EXE will also export to Connect the Dots and WORM file formats.
  9.    It is set up to create coiled strings of spheres that twist about a 
  10. circle a number of times and terminate at the point of origin. It generates
  11. a data file to be called from the users main PoV or Polyray input script
  12. file or as an input file for CTDS or WORM.
  13.  
  14. Files included:
  15.  
  16.    COIL.EXE       DOS executable program v2.1 
  17.    COIL.CPP       C++ source code for coil.exe v2.1
  18.    COIL.INC       Example generated data file of the default coil object
  19.    COIL.POV       Example PoV v1.0 main script file that calls COIL.INC
  20.    COIL.PI        Example Polyray main script file set up for a default coil
  21.    COIL.MAK       MS C++ v8.00 make file for COIL.CPP v2.1    
  22.    COIL.DOC       This file
  23.    
  24.    COIL_V20.C     Origional v2.0 C source code  
  25.    COIL_V20.PRJ   Origional BC++ v3.1 project file for COIL.C (v2.0)
  26.    COIL_V20.MAK   Origional BC++ v3.1 make file for COIL.C (v2.0) 
  27.    
  28.    These last 3 files must be renamed from COIL_V20 to COIL in order for
  29.    the respective PRJ and MAK files to function correctly w/the BC++ v3.1
  30.    compiler.  I have included these original files because the COIL.EXE v2.1 
  31.    program is based upon them.   -R. Bryerton 9/14/93
  32.    
  33.  
  34. Usage:
  35.  
  36.    The COIL program is easy to use since it is interactive. Just type COIL 
  37. at the DOS prompt and enter the parameters required. Most of the questions 
  38. are straight forward. Note that you can hit ENTER to accept the defaults.
  39.  
  40.    There are now more options with version 2.1 in the form of additional
  41. interactive choices and 4 command line options.  
  42.  
  43. The parameters requested are briefly defined as follows with defaults show 
  44. in brackets:
  45.  
  46. ------------------------ 'Interactive' options -----------------------------
  47.  
  48. Output format [POV]:   enter the file format for the coil object.  Choices 
  49.  are PoV-Ray, Polyray, CTDS, and WORM.
  50.  
  51. Shape type [Sphere]:   enter your choice for the object to use in the
  52.  creation of the coil. Choices are sphere, ellipsoid, box, y_cone,and 
  53.  y_cylinder. This option is only available for PoV and Polyray formats
  54.  and is accessed through the use of the -e command line option. (see below) 
  55.  
  56.  If you choose a shape other than Sphere, COIL will put #declared scale and 
  57.  rotate 'vectors' into the .inc file for more options. These vectors apply
  58.  to each object in the coil on an individual basis. (Flatten and stretch 
  59.  ellipsoids, for example.)
  60.  
  61. Output filname [coil.inc]:   enter the output file to be created. Note that 
  62.  this file does not contain all of the PoV or Polyray inputs required. You 
  63.  must #include it into a scene description file.  If you chose CTDS or WORM,
  64.  the resulting file will be ready for input into the respective target 
  65.  program.
  66.  
  67. Union name [coil]:   name of object union to be used to identify the created 
  68.  object. This applies only to PoV and Polyray.
  69.  
  70. Number of objects [100]:  total number of objects used to create the final 
  71.  coil object.
  72.  
  73. Number of objects in cross section [2]:  number of objects to be contained 
  74.    within the cross section of an imaginary torus about the center position. 
  75.    See illustration below. Objects are equally separated in minor angle.
  76.  
  77. Number of twists [2]:  number of twists the coil is to make within a single 
  78.    revolution about the center position (i.e., major radius).
  79.  
  80. Major radius [1.0]:  major radius of coil (i.e., center of torus).
  81.  
  82. Minor radius [0.25]:  minor radius of imaginary torus of sphere center 
  83.    positions.
  84.  
  85. Object 'radius' [0.25]:  size (radius for spheres) of the individual objects
  86.  that make up coil. The output of other shapes will be appropriately scaled
  87.  to remain consistent with the default sphere scaling.
  88.  
  89. Overall scale factor [1.0]:  scale factor for all x,y,z positions, but not 
  90.    the radius (size) of the individual objects.
  91.  
  92. ------------------------- Command Line options ------------------------------
  93.  
  94. -d#  Display mode           Enables a 2D (xy) display of the coil object
  95.                             as it is being created.  You MUST have a VGA
  96.                             display to use this option. Options are...
  97.                             1=640x480  2=800x600  3=1024x768... default is 1
  98.                             if -d is specified on the command line with no
  99.                             number or an invalid number
  100.                             SEE 'VERSION 2.1 NOTES' AT THE END OF THIS 
  101.                             DOCUMENT FOR **IMPORTANT** INFO ON THIS OPTION
  102.  
  103. -e   Extended menu mode     You will be given a choice of shapes to use to 
  104.                             build the coil object (cones, boxes, etc). 
  105.  
  106. -p#  Precision of numbers   Default is 6 decimal precision, which should be
  107.      used in output file    ok for almost every situation.  Valid range is
  108.                             2 to 9.  This applies to ALL output formats.
  109.  
  110. -h        HELP              Shows a brief summary of program options and 
  111. -help                       usage                     
  112. /? etc...            
  113.  
  114. Note that command line options are just that.  You can still enter COIL at 
  115. the command line and the program will run with the default options.
  116. ----------------------------------------------------------------------------
  117.                          
  118.                          
  119.                          
  120.                                            + <= 1st sphere center
  121.            object                        /
  122.            center                      /  minor radius and angle
  123.               + -------------------->+ -------------------
  124.                 major radius       /
  125.                                  /
  126.                                + <= 2nd sphere center
  127.  
  128.                Illustration of two spheres in cross section
  129.                          
  130.                          
  131.                          
  132. Source code:
  133.  
  134. COIL v2.1 was created using Microsoft C++ version 8.0, and is based on the
  135. original v2.0 C source code by Bill Kirby. The compiled program (COIL.EXE) 
  136. provided will work with an 8088 without a coprocessor or better. 
  137.  
  138. The COIL output has been tested with the Persistance of Vision (PoV)
  139. raytracer v1.0, Polyray v1.6, CTDS v2.3, and WORM v0.05a.  
  140.  
  141. Testing has included objects containing over 10,000 spheres. The example 
  142. PoV input file (coil.pov & coil.inc ) for a 320x200 image with 100 spheres
  143. and a plane requires 1 min 50 sec on a 386/387/40 using the 386 protected
  144. mode version of PoV-Ray v1.0.  The equivalent file in Polyray v1.6 takes
  145. about 2 min 5 sec on the same machine.  When rendering primitives other than
  146. spheres however, Polyray is easily 2x to 4x faster than POV, due to 
  147. Polyray's use of automatic bounds, I'd imagine.
  148.  
  149. Fragment of code for generation of sphere center positions from coil.c v2.0
  150.  
  151. /* Compute twisted coil object */
  152.  
  153.     for(i=0;i<steps;++i){      /* loop on number of spheres in object */
  154.       angle1 = 2 * PI * Ntube * (double)i/ (double)steps; /* major angle */
  155.       x1 = cos( angle1 );
  156.       y1 = sin( angle1 );
  157.       angle2 = (double)( Ntwist + 1.0/Ntube) * angle1; /* minor angle */
  158.       x2 = cos( angle2 );
  159.       z2 = sin( angle2);
  160.       xpos = k * ((Rad1 * x1) + (rad2 * x2 * x1));   \
  161.       ypos = k * ((Rad1 * y1) + (rad2 * x2 * y1));    > sphere center position
  162.       zpos = k * rad2 * z2;                          /
  163.       write_piece(xpos,ypos,zpos,radius);   /* sphere position and radius */
  164.     }
  165.  
  166.    Besides computing object positions, the code computes bounds for the 
  167. generated coil using the min and max coil shape x,y,z extent plus a 1% fudge
  168. factor to insure it encompasses the whole coil. The code is true brute force
  169. with little optimization.  This is justified since the code executes so 
  170. quickly. 
  171.  
  172. Enjoy
  173.  
  174. Bill Kirby
  175.  
  176. Bill Kirby        CIS [70711,2407], COMART forum
  177. 3527 Cornell Road
  178. Fairfax, VA 22030
  179.  
  180. BBS's visited:  You Can Call Me Ray             (708) 358-5611
  181.                 The Graphics Alternative        (510) 524-2780
  182.  
  183.  
  184. --------------------------NOTES ON VERSION 2.1-------------------------------
  185.  
  186. You MUST have a VGA display to use the -d option, which will display the 
  187. (approximate) coil object as it is being generated. This allows you to 
  188. experiment with some wild settings without having to render the object to
  189. see the resulting shape. Please note that, even if you specify a shape other
  190. than spheres, the graphic preview will show spheres.  Also, spheres in the 
  191. preview DO NOT appear evenly spaced due to the Z axis being ignored. You can
  192. render the included scene file, changing the rotation of the coil to <0 0 0>,
  193. and compare with the preview using ALL of the default menu choices to get a
  194. feel for the graphic preview.
  195.  
  196. >>>>>>>>>>>>>>>>>>>>>>>>>> IMPORTANT INFO <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  197.  
  198. DO NOT specify a resolution higher than your MONITOR can handle, as you risk
  199. the possibility of DAMAGE.  If you specify a resolution higher than your
  200. graphics card is capable of, the program will sense this and disable the 
  201. display while calculating the coil.
  202.  
  203. If you use the -e command line option, there will be #declared scale and 
  204. rotate 'vectors' included in the data file.  These vectors will act on each
  205. individual object, allowing you to flatten, stretch, or rotate EVERY object
  206. in the coil on an individual basis.  
  207.  
  208. Note that for POV, if you specify a rotation on more than 1 axis, it 
  209. will not work correctly, although POV won't complain.  This is stated in 
  210. the original POV docs, but I have not researched this fact any further.
  211. Experiment and see what works and what doesn't !!
  212.  
  213. Polyray WILL handle multiple axis rotations specified in the same vector.
  214.  
  215.  
  216.  
  217. ------------------------C++ SOURCE CODE NOTES--------------------------------
  218.  
  219. This program has been rewritten in C++ more as an exercise than out of 
  220. necessity. I would like to thank Bill Kirby, the original author of COIL 
  221. v2.0, for giving me permission to release this update on his code.
  222.  
  223. I originally wrote the update in C, but then decided to use C++'s object
  224. oriented environment, although my class implementation is somewhat less
  225. than optimal.   However, adding output formats by deriving classes from the
  226. base class is VERY simple, as you can see in the C++ source code. 
  227. The only drawback I can see is the file access speed. The equivalent C code
  228. using fprintf statements writes about 40% faster on my machine than C++
  229. insertion and extraction operators.  I chose to use these operators to 
  230. remain consistant with the rest of the program. Also, speed is not an issue 
  231. with this program, as the 'typical' 100 object coil writes in less than a
  232. second on most machines.
  233.  Note that this version of the program will only compile with the MS C++
  234. 8.00 compiler or higher due to the use of MS specific functions.  I will try
  235. to make the code 'portable' in the next few months if anyone is interested.
  236.  I am a beginner in C++ and would appreciate any observations you should 
  237. happen to make.
  238.  
  239. Any questions, comments, or otherwise are welcome.
  240.  
  241. Rob Bryerton    CIS [73747,433] GRAPHDEV
  242. 7/14/93
  243.  
  244. BBS's visited:  You Can Call Me Ray             (708) 358-5611